Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo
back

Agents

SafeNet Keycloak Agent

search

SafeNet Keycloak Agent

Please Note:

SafeNet Keycloak Agent

SafeNet Keycloak Agent is used for integration of a Keycloak Identity provider function (IDP) with SAS PCE. With this integration, SAS PCE provides multi-factor authentication in context of authentication requests received by the Keycloak IDP from SAML or OIDC integrated applications. This agent is also a key component of STA Hybrid Access Management Add-On based deployment.

SafeNet Keycloak Agent also supports Signal Sign-On (SSO) for applications integrated through Keycloak IDP. If an SSO exists for the same user and browser, SAS PCE is not invoked for token-based multi-factor authentication (MFA) and access is permitted when an access attempt reaches the Keycloak IDP. The access event is logged in the Keycloak IDP in this situation. If SSO is absent, SAS PCE is used for token-based MFA. If the authentication is successful, SSO is launched in the context of the users and the browser on the their system.

System Requirements

Operating System

The SafeNet Agent for Keycloak is supported by Java compatible operating systems (Linux or Windows).

Software Requirements

  • Oracle JDK 8 – JDK 11, OpenJDK 11

  • SAS PCE

  • Keycloak Server

Prerequisites

Configuration of these components is necessary for the installation of SafeNet Keycloak Agent.

SAS PCE

SafeNet Authentication Service PCE v3.16 and above is supported.

SAS API is not supported with SAS configured on PostgreSQL, hence SafeNet Keycloak Agent setup with SAS user federation does not work. But LDAP user federation works.

Keycloak Server

  • Ensure that the Keycloak server version 19.0.3 is deployed on the system along with administrator user setup. For installation and configuration, refer to the server section in the Keycloak Server Guide.

  • Refer to the Server Initialization section of the Keycloak Server Administrator Guide to setup the administrator user and master realm.

  • Ensure the Keycloak server's directory structure contains "bin/", "conf/", "lib/", "data/", "providers/" and "themes/".

    alt_text

  • You need to run Keycloak 19.0.3 with the old admin console. For that, you must disable the new console (admin2) by adding the following in your keycloak.conf file :

    features-disabled=admin2

    For more details, refer to https://www.keycloak.org/2022/07/keycloak-1900-released.

  • Ensure the SAS Token Validator service is accessible from the system where the Keycloak is configured.
    http(s):<sas-server-ip>:<port>/TokenValidator/TokenValidator.asmx

Keycloak Server Migration

In Keycloak version 19, Quarkus distribution is the default distribution. For those who have been using Keycloak Wildfly distribution, it is required to migrate to Quarkus distribution.

If you are using Keycloak Agent 1.2.0 with Keycloak version 15.0.2 (Wildfly), follow the steps below to migrate to Keycloak Agent 1.3.0 with Keycloak version 19.0.3 (Quarkus):

  1. Create a backup of the old installation, including configuration, themes, and others.

  2. Create a backup of the database using the instructions in the documentation for your relational database.

  3. Upgrade the Keycloak server. The database will no longer be compatible with the old server after the upgrade.

  4. If you need to reverse the upgrade, restore the old installation first, and then restore the database from the backup.

For more detail on migration procedure, see the Upgrading Guide version 19.0.3.

Terminologies

  • Keycloak Directory: Keycloak server installation directory.

  • Authentication Flow: An authentication flow is a container for all authentications, screens, and actions that are mandatory during login, registration, and other Keycloak workflows.

Package Contents

The SafeNet Keycloak Agent is a compressed zip|tar.gz file. The SafeNetKeycloakAgent Package contains:

  • Setup scripts

  • Binaries

  • Themes resources

  • SafeNet OTP Realm json file

  • Realm configuration and Authentication flows defined for SAS OTP Validation.

To unpack this file, run the unzip, gunzip or tar utilities.

alt_text

Keycloak SAS Providers (Keycloak SPIs)

On the functional level, the package updates the following modules on the pre-installed Keycloak server.

  • SafeNet OTP Authentication Flow – Customized authentication flow for OTP validation with SAS Token Validator service.

  • SafeNet Theme – Customized theme to define SafeNet HTML templates and stylesheets.

Set up SAS API for SAS PCE

This setup is mandatory when SAS is configured with MySQL database.

SAS API requests data from SAS PCE to dynamically update the SafeNet Keycloak Agent.

SAS API encounters an issue with MySQL database (MySQL EF6 DLL in GAC missing). It is a limitation of MySQL Connector 8.0.27.

When SafeNet Keycloak Agent is configured with SAS using MySQL database, follow below steps.

Before installation ensure that the following steps are performed:

  1. After installing SafeNet server, install MySQL 8.0.27 Connector.

  2. Configure SafeNet server with MySQL database.

  3. Copy the following text in a text file and save the file in the .ps1 file format:

    #Note that you should be running PowerShell as an Administrator
    [System.Reflection.Assembly]::Load("System.EnterpriseServices, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")

    $publish = New-Object System.EnterpriseServices.Internal.Publish
    $publish.GacInstall("C:\Program Files (x86)\MySQL\MySQL Connector Net 8.0.27\Assemblies\v4.5.2\MySql.Data.EntityFramework.dll")
    #If installing into the GAC on a server hosting web applications in IIS, you need to restart IIS for the #applications to pick up the change.
    Iisreset

  4. Run the .ps1 file, as an Administrator in the PowerShell.

  5. Reset IIS.

Points to Remember

  • Default location: System Directory:\Program Files (x86)\MySQL\MySQL Connector Net 8.0.27\<locate MySql.Data.EntityFramework.dll file>

  • If someone changes the directory location while installing the MySQL Connector, the above path also needs to be updated in the script.

  • Open the PowerShell script and change the path to where your DLL resides.

Configuration overview

Set up of SAS PCE is required for end to end setup and validation for STA Hybrid environment.